package com.meshnetics.gb.stack.core;

import java.io.IOException;
import java.util.Collection;

/**
 * Context with the ability to retrieve/add parameters by their code.
 * Also contains StackProfile support and the ability to save it.
 *
 * @author mmarkov
 */
public interface InformationBase extends Cloneable {
    /**
     * Returns the IBParameter with the given name or null if it is not found.
     *
     * @param name the name of the IBParameter to search for
     * @return the IbParameter with the given name or null if it is not found
     */
    IBParameter getParameter(String name);

    /**
     * Returns the IBParameter with the given code or null if it is not found.
     *
     * @param code the code of the IBParameter to search for
     * @return the IBParameter with the given code or null if it is not found
     */
    IBParameter getParameter(int code);

    /**
     * Returns the value of the IBParameter with the given name or null if it is not found.
     *
     * @param name the name of the IBParameter to search for
     * @return the value of the IBParameter with the given name or null if it is not found
     */
    Object getValue(String name);

    /**
     * Returns the value of the IBParameter with the given code or null if it is not found.
     *
     * @param code the code of the IBParameter to search for
     * @return the value of the IBParameter with the given code or null if it is not found
     */
    Object getValue(int code);

    /**
     * Adds the given IBParameter to the InformationBase.
     *
     * @param param the IBParameter to be set in the InformationBase
     * @return previous IBParameter with the same name or null if it was not set before
     */
    IBParameter addParameter(IBParameter param);

    /**
     * Removes the IBParameter with the given name from the InformationBase.
     *
     * @param name the name of the IBParamtere to be removed
     * @return the removed IBParameter or null if it was not set before
     */
    IBParameter removeParameter(String name);

    /**
     * Removes the IBParameter with the given code from the InformationBase.
     *
     * @param code the code of the IBParamtere to be removed
     * @return the removed IBParameter or null if it was not set before
     */
    IBParameter removeParameter(int code);

    /**
     * Returns all paramters existing in this InformationBase.
     *
     * @return all paramters existing in this InformationBase
     */
    Collection getParameters();

    /**
     * Resets all the parameters in the InformationBase to their default values.
     */
    void reset();

    /**
     * Resets an IBParameter with the given name to it's default value.
     *
     * @param name name of the IBParamater to reset
     */
    void reset(String name);

    /**
     * Replaces the values of this InformationBase parameters with the ones from the given
     * InformationBase.
     *
     * @param ib InformationBase to get the parameters from
     */
    void setData(InformationBase ib);

    /**
     * Saves the current state of InformationBase to the file.
     *
     * @param file the name of the file to save the state
     * @throws IOException if any I/O error occurs 
     */
    void save(String file) throws IOException;

    /**
     * Returns a copy of this InformationBase.
     *
     * @return a copy of this InformationBase
     */
    Object clone();
}
